---
title: Imágenes
description: Aprende cómo usar imágenes en Astro.
i18nReady: true
---
import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import RecipeLinks from "~/components/RecipeLinks.astro";
import { Steps } from '@astrojs/starlight/components'
import ReadMore from '~/components/ReadMore.astro';

¡Astro ofrece varias formas para que uses imágenes en tu sitio, ya sea que estén almacenadas localmente dentro de tu proyecto, enlazadas desde una URL externa o gestionadas en un CMS o CDN!

Astro proporciona componentes integrados [`<Image />`](#image-) y [`<Picture />`](#picture-), procesamiento de la [sintaxis de imágenes Markdown](#imágenes-en-archivos-markdown) (`![]()`), [Componentes SVG](#componentes-svg), y [una función generadora de imágenes](#generando-imágenes-con-getimage) para optimizar y/o transformar tus imágenes. Además, puedes configurar [redimensionamiento automático de imágenes responsivas](#imagenes-responsivas) de forma predeterminada, o establecer propiedades responsivas en componentes de imágenes e imágenes individuales.

Siempre puedes optar por utilizar imágenes y archivos SVG utilizando elementos HTML nativos en archivos `.astro` o Markdown, o la forma estándar para tu tipo de archivo (por ejemplo, `<img />` en MDX y JSX). Sin embargo, Astro no realiza ningún procesamiento ni optimización de estas imágenes.

Astro tampoco ofrece compatibilidad nativa con vídeos, por lo que recomendamos elegir un [servicio de alojamiento de vídeos](/es/guides/media/) para gestionar las necesidades de optimización y transmisión de contenido de vídeo.

<ReadMore>Consulta la referencia completa de la API para los componentes [`<Image />`](/es/reference/modules/astro-assets/#image-) y [`<Picture />`](/es/reference/modules/astro-assets/#picture-).</ReadMore>

## Dónde guardar las imágenes

### `src/` vs. `public/`

Recomendamos que las imágenes locales se mantengan en `src/` cuando sea posible, para que Astro pueda transformar, optimizar y empaquetarlas. Los archivos en el directorio `/public` siempre se sirven o copian tal como están en la carpeta de construcción, sin ningún procesamiento.

Tus imágenes locales almacenadas en `src/` pueden ser utilizadas por todos los archivos en tu proyecto: `.astro`, `.md`, `.mdx`, `.mdoc` y otros frameworks UI. Las imágenes pueden almacenarse en cualquier carpeta, incluida junto a tu contenido.

Almacena tus imágenes en la carpeta `public/` si deseas evitar cualquier tipo de procesamiento o para tener un enlace público directo a ellas.

### Imágenes remotas

También puedes optar por almacenar tus imágenes de forma remota, en un [sistema de gestión de contenido (CMS)](/es/guides/cms/) o en una [plataforma de gestión de assets digitales (DAM)](/es/guides/media/). Astro puede obtener tus datos de forma remota utilizando APIs o mostrar imágenes desde su ruta completa de URL.

Para una protección adicional al tratar con fuentes externas, las imágenes remotas solo se procesarán desde [fuentes de imágenes autorizadas](#autorizando-imágenes-remotas) especificadas en tu configuración. Sin embargo, cualquier imagen remota puede ser mostrada.

## Imágenes en archivos `.astro`

<p>

**Opciones:** `<Image />`, `<Picture />`, `<img>`, `<svg>`, componentes SVG
</p>

El lenguaje de plantillas de Astro te permite renderizar imágenes optimizadas con el componente [`<Image />`](/es/reference/modules/astro-assets/#image-) y generar múltiples tamaños y formatos con el componente [`<Picture />`](/es/reference/modules/astro-assets/#picture-). Ambos componentes también aceptan [propiedades de imagen responsivas](#imagenes-responsivas) para redimensionarse según el tamaño del contenedor y responder al tamaño y la resolución de la pantalla del dispositivo.

Además, puedes importar y utilizar [archivos SVG como componentes de Astro](#componentes-svg) en componentes `.astro`.

Todas las etiquetas HTML nativas, incluidas `<img>` y `<svg>`, también están disponibles en componentes `.astro`. [Las imágenes renderizadas con etiquetas HTML](#mostrar-imágenes-sin-procesar-con-la-etiqueta-html-img) no serán procesadas (por ejemplo, optimizadas, transformadas) y se copiarán en tu carpeta de construcción tal cual.

Para todas las imágenes en archivos `.astro`, **el valor del atributo `src` de la imagen se determina por la ubicación de tu archivo de imagen**:

- Una imagen local de la carpeta `src/` de tu proyecto utiliza una importación desde la ruta relativa del archivo.

  Los componentes de Image y Picture utilizan la importación nombrada directamente (por ejemplo, `src={rocket}`), mientras que la etiqueta `<img>` utiliza la propiedad del objeto `src` de la importación (por ejemplo, `src={rocket.src}`).

- Las imágenes remotas y `public/` utilizan una ruta URL.

  Proporciona una URL completa para imágenes remotas (por ejemplo, `src="https://www.example.com/images/my-remote-image.jpg"`), o una ruta URL relativa en tu sitio que corresponda a la ubicación de tu archivo en la carpeta `public/` (por ejemplo, `src="/images/my-public-image.jpg"` para una imagen ubicada en `public/images/my-public-image.jpg`).

```astro title="src/pages/blog/my-images.astro"
---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="Un pájaro sentado sobre un nido de huevos."/>
<Image src="/images/bird-in-public-folder.jpg" alt="Un pájaro." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="Un pájaro." width="50" height="50" />

<img src={localBirdImage.src} alt="Un pájaro sentado sobre un nido de huevos.">
<img src="/images/bird-in-public-folder.jpg" alt="Un pájaro.">
<img src="https://example.com/remote-bird.jpg" alt="Un pájaro.">
```

<ReadMore>Consulta la referencia completa de la API para los componentes [`<Image />`](/es/reference/modules/astro-assets/#image-) y [`<Picture />`](/es/reference/modules/astro-assets/#picture-) incluidas las propiedades obligatorias y opcionales.</ReadMore>

<RecipeLinks slugs={["es/recipes/dynamically-importing-images" ]}/>


## Imágenes en archivos Markdown

<p>

**Opciones:** `![]()`, `<img>` (con imágenes públicas o remotas)
</p>

Utiliza la sintaxis estándar de Markdown `![alt](src)` en tus archivos `.md`. Tus imágenes locales almacenadas en `src/` y las imágenes remotas serán procesadas y optimizadas. Cuando [configures imágenes responsivas globalmente](/es/reference/configuration-reference/#image-options), estas imágenes también serán [responsivas](#imagenes-responsivas).

Las imágenes almacenadas en la carpeta `public/` nunca se optimizan.

```md
<!-- src/pages/post-1.md -->

# Mi página Markdown

<!-- Imagen local almacenada en src/assets/ -->
<!-- Usa una ruta de archivo relativa o un alias de importación -->
![Un cielo estrellado.](../assets/stars.png)

<!-- Imagen almacenada en public/images/ -->
<!-- Usa la ruta de archivo relativa a public/ -->
![Un cielo estrellado.](/images/stars.png)

<!-- Imagen remota en otro servidor -->
<!-- Usa la URL completa de la imagen -->
![Astro](https://example.com/images/remote-image.png)
```

La etiqueta HTML `<img>` también se puede utilizar para mostrar imágenes almacenadas en `public/` o imágenes remotas sin necesidad de optimizar ni procesar las imágenes. Sin embargo, `<img>` no es compatible con las imágenes locales en `src`.

Los componentes `<Image />` y `<Picture />` no están disponibles en archivos `.md`. Si necesitas más control sobre los atributos de tus imágenes, te recomendamos usar [la integración MDX de Astro](/es/guides/integrations-guide/mdx/) para agregar soporte para el formato de archivo `.mdx`. MDX permite [opciones adicionales de imagen](#imágenes-en-archivos-mdx) disponibles en MDX, incluyendo la combinación de componentes con la sintaxis Markdown.

## Imágenes en archivos MDX

<p>

**Opciones:** `<Image />`, `<Picture />`, `<img>`, `![]()`, componentes SVG
</p>

Puedes utilizar los componentes `<Image />` y `<Picture />` de Astro en tus archivos `.mdx` importando tanto el componente como tu imagen. Úsalos tal y como se utilizan [en los archivos `.astro`](#imágenes-en-archivos-astro). La etiqueta JSX `<img />` también es compatible con imágenes sin procesar y [utiliza la misma importación de imágenes que la etiqueta HTML `<img>`](#mostrar-imágenes-sin-procesar-con-la-etiqueta-html-img).

Además, se admite la [sintaxis estándar de Markdown `![alt](src)`](#imágenes-en-archivos-markdown) sin necesidad de importarla.

```mdx title="src/pages/post-1.mdx"
---
title: Mi título de página
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# Mi página MDX

// Imagen local guardada en la misma carpeta
![Houston en estado salvaje](houston.png)

// Imagen local almacenada en src/assets/
<Image src={rocket} alt="Un cohete en el espacio." />
<img src={rocket.src} alt="Un cohete en el espacio." />
![Un cohete en el espacio](../assets/rocket.png)

// Imagen almacenada en public/images/
<Image src="/images/stars.png" alt="Un cielo estrellado." />
<img src="/images/stars.png" alt="Un cielo estrellado." />
![Un cielo estrellado.](/images/stars.png)

// Imagen remota en otro servidor
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)

```

<ReadMore>Consulta la referencia completa de la API para los componentes [`<Image />`](/es/reference/modules/astro-assets/#image-) y [`<Picture />`](/es/reference/modules/astro-assets/#picture-).</ReadMore>

## Imágenes en componentes UI de frameworks

<p>

**Opciones de imagen:** la sintaxis de imagen propia del framework (por ejemplo, `<img />` en JSX, `<img>` en Svelte)
</p>

[Las imágenes locales deben importarse primero](#mostrar-imágenes-sin-procesar-con-la-etiqueta-html-img) para acceder a sus propiedades de imagen, como `src`. Luego, se pueden renderizar como lo harías normalmente en la sintaxis de imagen de ese framework:

```jsx title="src/components/ReactImage.jsx"
import stars from "../assets/stars.png";

export default function ReactImage() {
  return (
    <img src={stars.src} alt="Un cielo estrellado." />
  )
}
```

```svelte title="src/components/SvelteImage.svelte"
<script>
  import stars from '../assets/stars.png';
</script>

<img src={stars.src} alt="Un cielo estrellado." />

```

Los componentes de Astro (por ejemplo, `<Image />`, `<Picture />`, componentes SVG) no están disponibles dentro de los componentes de framework UI porque [una isla de cliente debe contener solo código válido para su propio framework](/es/guides/framework-components/#can-i-use-astro-components-inside-my-framework-components).

Pero, puedes pasar el contenido estático generado por estos componentes a un componente de framework dentro de un archivo `.astro` [como hijos](/es/guides/framework-components/#passing-children-to-framework-components) o utilizando un [`<slot/>` nombrado](/es/guides/framework-components/#can-i-use-astro-components-inside-my-framework-components):

```astro title="src/components/ImageWrapper.astro"
---
import ReactComponent from './ReactComponent.jsx';
import { Image } from 'astro:assets';
import stars from '~/stars/docline.png';
---

<ReactComponent>
  <Image src={stars} alt="Un cielo estrellado." />
</ReactComponent>
```


## Componentes Astro para imágenes

Astro proporciona dos componentes integrados para imágenes (`<Image />` y `<Picture />`) y también te permite importar archivos SVG y usarlos como componentes Astro. Estos componentes se pueden usar en cualquier archivo que pueda importar y renderizar componentes `.astro`.

### `<Image />`

Utiliza el componente integrado `<Image />` para mostrar versiones optimizadas de:

- tus imágenes locales ubicadas dentro de la carpeta `src/`
- [imágenes remotas configuradas](#autorizando-imágenes-remotas) de fuentes autorizadas

`<Image />` puede transformar las dimensiones, el tipo de archivo y la calidad de una imagen local o remota autorizada para controlar la imagen que se muestra. Esta transformación se produce en el momento de la compilación de las páginas prerenderizadas. Cuando tu página se renderiza bajo demanda, esta transformación se produce sobre la marcha cuando se visualiza la página. La etiqueta `<img>` resultante incluye los atributos `alt`, `loading` y `decoding`, e infiere las dimensiones de la imagen para evitar el desplazamiento acumulativo del diseño (CLS).

:::note[¿Qué es el Desplazamiento Acumulativo de Diseño?]
[Desplazamiento Acumulativo de Diseño (CLS)](https://web.dev/cls/) es una métrica de Core Web Vital para medir cuánto se ha desplazado el contenido de tu página durante la carga. El componente `<Image />` optimiza para el CLS al establecer automáticamente el `ancho` y el `alto` correctos para tus imágenes locales.
:::

```astro title="src/components/MyComponent.astro"
---
// Importa el componente Image y la imagen
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // La imagen es 1600x900
---

<!-- `alt` es obligatorio en el componente Imagen -->
<Image src={myImage} alt="Una descripción de mi imagen." />
```

```html
<!-- Salida prerenderizada -->
<!-- La imagen está optimizada, se aplican los atributos adecuados -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="Una descripción de mi imagen."
/>

<!-- Salida renderizada bajo demanda-->
<!-- src utilizará un endpoint generado bajo demanda-->
<img
  src="/_image?href=%2F_astro%2Fmy_image.hash.webp&amp;w=1600&amp;h=900&amp;f=webp"
  <!-- ... -->
/>
```

El componente `<Image />` acepta [varias propiedades de componente](/es/reference/modules/astro-assets/#propiedades-de-la-imagen) así como cualquier atributo aceptado por la etiqueta HTML `<img>`.

El siguiente ejemplo proporciona una `clase` al componente de imagen que se aplicará al elemento `<img>` final.

```astro title="src/pages/index.astro" 'class="mi-clase"'
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---

<!-- `alt` es obligatorio en el componente Imagen -->
<Image src={myImage} alt="" class="mi-clase" />
```

```html 'class="mi-clase"'
<!-- Salida prerenderizada -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="mi-clase"
  alt=""
/>

```

:::tip
También puedes usar el componente `<Image />` para imágenes en la carpeta `public/`, o imágenes remotas no configuradas específicamente en tu proyecto, incluso si estas imágenes no serán optimizadas o procesadas. La imagen resultante será la misma que usar la etiqueta HTML `<img>`.

Sin embargo, usar el componente de imagen para todas las imágenes proporciona una experiencia de autoría consistente y previene el Desplazamiento Acumulativo de Diseño (CLS) incluso para tus imágenes no optimizadas.
:::

### `<Picture />`

<p><Since v="3.3.0" /></p>

Usa el componente integrado `<Picture />` para generar una etiqueta `<picture>` con múltiples formatos y/o tamaños de tu imagen. Esto te permite especificar formatos de archivo preferidos para mostrar y, al mismo tiempo, proporcionar un formato de respaldo. Al igual que el [componente `<Image />`](#image-), las imágenes se procesarán en el momento de la construcción para las páginas prerenderizadas. Cuando tu página se renderiza bajo demanda, el procesamiento ocurrirá sobre la marcha cuando se visualice la página.

El siguiente ejemplo utiliza el componente `<Picture />` para transformar un archivo `.png` local en un formato `avif` y `webp` compatible con la web, así como en el `<img>` `.png` que se puede mostrar como respaldo cuando sea necesario:

```astro title="src/pages/index.astro"
---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // La imagen es de 1600x900
---

<!-- `alt` es obligatorio en el componente Picture -->
<Picture src={myImage} formats={['avif', 'webp']} alt="Una descripción de mi imagen." />
```

```html
<!-- Salida prerenderizada -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Una descripción de mi imagen."
  />
</picture>
```

<ReadMore>Consulta los detalles de las [propiedades del componente `<Picture />`](/es/reference/modules/astro-assets/#propiedades-de-picture) en la referecia `astro:assets`</ReadMore>

### Imagenes responsivas

<p><Since v="5.10.0" /></p>

Las imágenes responsivas son imágenes que se ajustan para mejorar el rendimiento en diferentes dispositivos. Estas imágenes pueden cambiar de tamaño para adaptarse a su contenedor y pueden servirse en diferentes tamaños según el tamaño y la resolución de la pantalla de tu visitante.

Con [propiedades de imagen responsivas](/es/reference/modules/astro-assets/#propiedades-de-imagen-responsiva) aplicadas a los componentes `<Image />` o `<Picture />`, Astro generará automáticamente los valores `srcset` y `sizes` requeridos para tus imágenes y aplicará los [estilos necesarios para garantizar que se redimensionen correctamente](#estilos-para-imágenes-responsivas).

Cuando este comportamiento responsivo se [configura globalmente](/es/reference/configuration-reference/#image-options), se aplicará a todos los componentes de imagen y también a cualquier imagen local y remota que utilice [la sintaxis Markdown `![]()`](#imágenes-en-archivos-markdown).

Las imágenes en tu carpeta `public/` nunca se optimizan, y las imágenes responsivas no son compatibles.

:::note
Una sola imagen responsiva generará múltiples imágenes de diferentes tamaños para que el navegador pueda mostrar la mejor a tu visitante.

Para las páginas prerenderizadas, esto ocurre durante la construcción y puede aumentar el tiempo de construcción de tu proyecto, especialmente si tienes un gran número de imágenes.

Para las páginas renderizadas bajo demanda, las imágenes se generan según sea necesario cuando se visita una página. Esto no tiene impacto en los tiempos de construcción, pero puede aumentar el número de transformaciones de imágenes realizadas cuando se muestra una imagen. Dependiendo de tu servicio de imágenes, esto puede incurrir en costos adicionales.
:::

<ReadMore>Consulta los detalles de las [imágenes responsivas en la documentación de MDN](https://developer.mozilla.org/es/docs/Web/HTML/Guides/Responsive_images).</ReadMore>

#### Salida HTML generada para imágenes responsivas

Cuando un diseño está configurado, ya sea por defecto o en un componente individual, las imágenes tienen atributos `srcset` y `sizes` generados automáticamente en función de las dimensiones de la imagen y el tipo de diseño. Las imágenes con diseños `constrained` y `full-width` tendrán estilos aplicados para garantizar que se redimensionen de acuerdo con su contenedor.

```astro title="src/components/MyComponent.astro"
---
import { Picture } from "astro:assets";
import myImage from "../my_image.png";
---
<Image src={myImage} alt="Una descripción de mi imagen." layout='constrained' width={800} height={600} />
```

Este componente `<Image />` generará la siguiente salida HTML en una página prerenderizada:

```html
<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="Una descripción de mi imagen."
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>
```

### Estilos para imágenes responsivas

Configurar [`image.responsiveStyles: true`](/es/reference/configuration-reference/#image-options) aplica un pequeño número de estilos globales para garantizar que tus imágenes se redimensionen correctamente. En la mayoría de los casos, querrás habilitar esto como valor predeterminado; tus imágenes no serán responsivas sin estilos adicionales.

Sin embargo, si prefieres manejar el estilo de las imágenes responsivas tú mismo, o necesitas [sobrescribir estos valores predeterminados al usar Tailwind 4](#imágenes-responsivas-con-tailwind-4), deja configurado el valor predeterminado `false`.

Los estilos globales aplicados por Astro dependerán del tipo de diseño y están diseñados para producir el mejor resultado para los atributos `srcset` y `sizes` generados. Estos son los estilos predeterminados:

```css title="Estilos para imágenes responsivas"
:where([data-astro-image]) {
	object-fit: var(--fit);
	object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
	width: 100%;
}
:where([data-astro-image='constrained']) {
	max-width: 100%;
}
```

Los estilos utilizan la [pseudo-clase `:where()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where), que tiene una [especificidad](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity) de 0, lo que significa que es fácil de sobrescribir con tus propios estilos. Cualquier selector CSS tendrá una especificidad más alta que `:where()`, por lo que puedes sobrescribir fácilmente los estilos agregando tus propios estilos para dirigirte a la imagen.

Puedes sobrescribir los estilos `object-fit` y `object-position` en una base por imagen configurando las propiedades `fit` y `position` en el componente `<Image />` o `<Picture />`.

#### Imágenes responsivas con Tailwind 4

Tailwind 4 es compatible con los estilos responsivos predeterminados de Astro. Sin embargo, Tailwind utiliza [capas de cascada](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer), lo que significa que sus reglas siempre tienen una especificidad más baja que las reglas que no utilizan capas, incluidos los estilos responsivos de Astro. Por lo tanto, el estilo de Astro tendrá prioridad sobre el estilo de Tailwind. Para utilizar las reglas de Tailwind en lugar del estilo predeterminado de Astro, no habilites [los estilos responsivos predeterminados de Astro](/es/reference/configuration-reference/#image-options).


### Componentes SVG
<p><Since v="5.7.0" /></p>

Astro te permite importar archivos SVG y utilizarlos como componentes de Astro. Astro integrará el contenido SVG en tu salida HTML.

Referencia la importación predeterminada de cualquier archivo `.svg` local. Dado que esta importación se trata como un componente de Astro, debes usar las mismas convenciones (por ejemplo, capitalización) que al [usar etiquetas dinámicas](/es/reference/astro-syntax/#etiquetas-dinámicas).

```astro title="src/components/MyAstroComponent.astro"
---
import Logo from './path/to/svg/file.svg';
---

<Logo />
```

Tu componente SVG, como `<Image />` o cualquier otro componente de Astro, no está disponible dentro de los componentes de UI framework, pero puede [ser pasado a un componente de framework](#imágenes-en-componentes-ui-de-frameworks) dentro de un componente `.astro`.

#### Atributos del componente SVG

Puedes pasar propiedades como `width`, `height`, `fill`, `stroke`, y cualquier otro atributo aceptado por el [elemento `<svg>` nativo](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg). Estos atributos se aplicarán automáticamente al elemento `<svg>` subyacente. Si una propiedad está presente en el archivo `.svg` original y se pasa al componente, el valor pasado al componente sobrescribirá el valor original.


```astro title="src/components/MyAstroComponent.astro"
---
import Logo from '../assets/logo.svg';
---

<Logo width={64} height={64} fill="currentColor" />
```

#### Tipo `SvgComponent`

<Since v="5.14.0" />

Puedes hacer cumplir la seguridad de tipos para tus activos `.svg` utilizando el tipo `SvgComponent`:

```astro title="src/components/Logo.astro"
---
import type { SvgComponent } from "astro/types";
import HomeIcon from './Home.svg'

interface Link {
	url: string
	text: string
	icon: SvgComponent
}

const links: Link[] = [
	{
		url: '/',
		text: 'Home',
		icon: HomeIcon
	}
]
---
```

### Creando componentes de imagen personalizados

Puedes crear un componente de imagen reutilizable y personalizado envolviendo el componente `<Image />` o `<Picture />` en otro componente de Astro. Esto te permite establecer atributos y estilos predeterminados solo una vez.

Por ejemplo, podrías crear un componente para las imágenes de tus publicaciones de blog que reciba atributos como props y aplique estilos consistentes a cada imagen:

```astro title="src/components/BlogPostImage.astro"
---
import { Image } from 'astro:assets';

const { src, ...attrs } = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>
```

## Mostrar imágenes sin procesar con la etiqueta HTML `<img>`

La [sintaxis de plantilla de Astro](/es/reference/astro-syntax/) también admite escribir una etiqueta `<img>` directamente, con control total sobre su salida final. Estas imágenes no serán procesadas ni optimizadas. Acepta todas las propiedades de la etiqueta HTML `<img>`, y la única propiedad requerida es `src`. Sin embargo, se recomienda encarecidamente incluir [la propiedad `alt` para accesibilidad](#texto-alternativo).

### imágenes en `src/`

Las imágenes locales deben importarse desde la ruta relativa del archivo `.astro` existente, o puedes configurar y usar un [alias de importación](/es/guides/imports/#aliases). Luego, puedes acceder a las propiedades `src` y otras de la imagen para usarlas en la etiqueta `<img>`.

Los activos de imagen importados coinciden con la siguiente firma:

```ts
interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}
```

El siguiente ejemplo utiliza las propias propiedades `height` y `width` de la imagen para evitar el cambio de diseño acumulativo (CLS) y mejorar los Core Web Vitals:

```astro title="src/pages/posts/post-1.astro" "myDog.width" "myDog.height"
---
// importa imágenes locales
import myDog from '../../images/pets/local-dog.jpg';
---
// accede a las propiedades de la imagen
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="Un perro ladrando." />
```

### Imágenes en `public/`
Para las imágenes ubicadas dentro de `public/`, utiliza la ruta del archivo de la imagen relativa a la carpeta pública como el valor de `src`:

```astro '"/images/public-cat.jpg"'
<img src="/images/public-cat.jpg" alt="Un gato durmiendo." >
```

### Imágenes remotas

Para las imágenes remotas, utiliza la URL completa de la imagen como el valor de `src`:

```astro '"https://example.com/remote-cat.jpg"'
<img src="https://example.com/remote-cat.jpg" alt="Un gato durmiendo." >
```

### Elegir `<Image />` vs `<img>`

El componente `<Image />` optimiza tu imagen e infiere el ancho y la altura (para las imágenes que puede procesar) en función de la relación de aspecto original para evitar CLS. Es la forma preferida de usar imágenes en archivos `.astro` siempre que sea posible.

Utiliza el elemento HTML `<img>` cuando no puedas usar el componente `<Image />`, por ejemplo:
  - para formatos de imagen no compatibles
  - cuando no quieras que tu imagen sea optimizada por Astro
  - para acceder y cambiar el atributo `src` dinámicamente del lado del cliente


## Usando imágenes de un CMS o CDN

Los CDNs de imágenes funcionan con [todas las opciones de imagen de Astro](#imágenes-en-archivos-astro). Utiliza la URL completa de una imagen como el atributo `src` en el componente `<Image />`, una etiqueta `<img>` o en notación Markdown. Para la optimización de imágenes con imágenes remotas, también [configura tus dominios autorizados o patrones de URL](#autorizando-imágenes-remotas).

Alternativamente, el CDN puede proporcionar sus propios SDK para integrarse más fácilmente en un proyecto Astro. Por ejemplo, Cloudinary admite un [SDK de Astro](https://astro.cloudinary.dev/) que te permite agregar imágenes fácilmente con su componente `CldImage` o un [SDK de Node.js](https://cloudinary.com/documentation/node_integration) que puede generar URL para usar con una etiqueta `<img>` en un entorno de Node.js.

<ReadMore>Consulta la referencia completa de la API para los componentes [`<Image />`](/es/reference/modules/astro-assets/#image-) y [`<Picture />`](/es/reference/modules/astro-assets/#picture-).</ReadMore>

## Autorizando imágenes remotas

Puedes configurar listas de dominios y patrones de URL de origen de imágenes autorizados para la optimización de imágenes utilizando [`image.domains`](/es/reference/configuration-reference/#imagedomains) y [`image.remotePatterns`](/es/reference/configuration-reference/#imageremotepatterns). Esta configuración es una capa adicional de seguridad para proteger tu sitio al mostrar imágenes de una fuente externa.

Las imágenes remotas de otras fuentes no serán optimizadas, pero usar el componente `<Image />` para estas imágenes evitará el cambio de diseño acumulativo (CLS).

Por ejemplo, la siguiente configuración solo permitirá que las imágenes remotas de `astro.build` sean optimizadas:

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});
```

La siguiente configuración solo permitirá que las imágenes remotas de hosts HTTPS sean optimizadas:

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});
```

## Imágenes en colecciones de contenido

Puedes declarar una imagen asociada para una entrada de colecciones de contenido, como la imagen de portada de una publicación de blog, en tu frontmatter utilizando su ruta relativa a la carpeta actual:

```md title="src/content/blog/my-post.md" {3}
---
title: "Mi primer post de blog"
cover: "./firstpostcover.jpeg" # va a resolver a "src/content/blog/firstpostcover.jpeg"
coverAlt: "Una fotografía de un atardecer detrás de una cordillera."
---

Contenido del post de blog.
```

El helper `image` para el esquema de colecciones de contenido te permite validar e importar la imagen.

```ts title="src/content.config.ts"
import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
	schema: ({ image }) => z.object({
		title: z.string(),
		cover: image(),
		coverAlt: z.string(),
	}),
});

export const collections = {
	blog: blogCollection,
};
```

La imagen será importada y transformada en metadatos, lo que te permitirá pasarla como `src` a `<Image/>`, `<img>`, o `getImage()` en un componente Astro.

El siguiente ejemplo muestra una página de índice de blog que renderiza la foto de portada y el título de cada publicación de blog a partir del esquema anterior:

```astro title="src/pages/blog.astro" {10}
---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---

{
	allBlogPosts.map((post) => (
		<div>
			<Image src={post.data.cover} alt={post.data.coverAlt} />
			<h2>
				<a href={"/blog/" + post.slug}>{post.data.title}</a>
			</h2>
		</div>
	))
}
```

## Generando imágenes con `getImage()`

La función `getImage()` está destinada a generar imágenes que se utilizarán en otros lugares que no sean directamente en HTML, por ejemplo, en una [Ruta API](/es/guides/endpoints/#server-endpoints-api-routes). Cuando necesites opciones que los componentes `<Picture>` y `<Image>` no admiten actualmente, puedes usar la función `getImage()` para crear tu propio componente `<Image />` personalizado.

<ReadMore>Consulta más en la [referencia de `getImage()`](/es/reference/modules/astro-assets/#getimage).</ReadMore>

<RecipeLinks slugs={["es/recipes/build-custom-img-component" ]}/>

## Texto Alternativo

No todos los usuarios pueden ver las imágenes de la misma manera, por lo que la accesibilidad es una preocupación especialmente importante al usar imágenes. Usa el atributo `alt` para proporcionar [texto alternativo descriptivo](https://www.w3.org/WAI/tutorials/images/) para las imágenes.

Este atributo es obligatorio tanto para los componentes `<Image />` como para los `<Picture />`. Si no se proporciona texto alternativo, se mostrará un mensaje de error útil recordándote que incluyas el atributo `alt`.

Si la imagen es meramente decorativa (es decir, no contribuye a la comprensión de la página), establece `alt=""` para que los lectores de pantalla sepan que ignoren la imagen.

## Servicio de imagen predeterminado

[Sharp](https://github.com/lovell/sharp) es el servicio de imagen predeterminado utilizado para `astro:assets`. Puedes configurar aún más el servicio de imagen utilizando la opción [`image.service`](/es/reference/configuration-reference/#imageservice).

:::note
Al usar un [gestor de paquetes estricto](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) como `pnpm`, es posible que debas instalar Sharp manualmente en tu proyecto, aunque sea una dependencia de Astro:

```bash
pnpm add sharp
```
:::

### Configurar un servicio de paso a través no-op

Si tu [adaptador](https://astro.build/integrations/?search=&categories%5B%5D=adapters) no es compatible con la optimización de imágenes Sharp integrada de Astro (por ejemplo, Deno, Cloudflare), puedes configurar un servicio de imagen no-op para permitirte usar los componentes `<Image />` y `<Picture />`. Ten en cuenta que Astro no realiza ninguna transformación y procesamiento de imágenes en estos entornos. Sin embargo, aún puedes disfrutar de los otros beneficios de usar `astro:assets`, incluido el desplazamiento acumulativo de diseño (CLS) nulo, el atributo `alt` impuesto y una experiencia de autoría coherente.

Configura el `passthroughImageService()` para evitar el procesamiento de imágenes de Sharp:

```js title="astro.config.mjs" ins={4-6} "passthroughImageService"
import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});
```

## Caché de imágenes

Astro almacena los activos de imagen procesados en un directorio de caché durante las compilaciones del sitio, tanto para imágenes locales como para [imágenes remotas de fuentes autorizadas](#autorizando-imágenes-remotas). Al preservar el directorio de caché entre compilaciones, los activos procesados se reutilizan, mejorando el tiempo de compilación y el uso del ancho de banda.

El directorio de caché predeterminado es `./node_modules/.astro`, sin embargo, esto se puede cambiar utilizando la configuración [`cacheDir`](/es/reference/configuration-reference/#cachedir).

### Imágenes remotas

Las imágenes remotas en la caché de activos se gestionan en función de [HTTP Caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching) y respetan el [Cache-Control header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) devuelto por el servidor remoto.
Las imágenes se almacenan en caché si el encabezado Cache-Control lo permite y se utilizarán hasta que ya no estén [frescas](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#fresh_and_stale_based_on_age).

#### Revalidación

<p><Since v="5.1.0" /></p>

La [Revalidación](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#validation) reduce el uso de ancho de banda y el tiempo de compilación al verificar con el servidor remoto si una imagen en caché caducada sigue estando actualizada. Si el servidor indica que la imagen sigue siendo fresca, se reutiliza la versión en caché; de lo contrario, se vuelve a descargar la imagen.

La revalidación requiere que el servidor remoto envíe los encabezados [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) y/o [Etag (etiqueta de entidad)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) con sus respuestas. Esta función está disponible para servidores remotos que admiten los encabezados [If-Modified-Since](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since) y [If-None-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match).

## Integraciones de la comunidad

Hay varias [integraciones de imágenes de la comunidad](https://astro.build/integrations?search=images) de terceros para optimizar y trabajar con imágenes en tu proyecto Astro.
